home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 332_01 / curses.3 < prev    next >
Text File  |  1988-01-01  |  15KB  |  299 lines
  1. CURSES(3)        MS-DOS Programmer's Manual          CURSES(3)
  2.  
  3. NAME
  4.    curses - screen/window management library
  5.  
  6. DESCRIPTION
  7.    Curses is a library of screen and window management routines. It is modeled
  8.    after the UNIX curses and ncurses libraries. Normally, programs written for
  9.    PCcurses should be easily ported to UNIX, and vice versa.
  10.  
  11.    To use the routines, the function initscr() must first be called. This cre-
  12.    ates two 'windows' for the user: stdscr and curscr. Stdscr is the default
  13.    window for the user to make changes on, and curscr reflects the current
  14.    contents of the physical display screen. The user writes or edits the std-
  15.    scr window to his liking, then calls the refresh() function to make curscr
  16.    and the physical screen look like stdscr. When the user program terminates,
  17.    it should call the endwin() function to restore things to normal.
  18.  
  19.    There are all sorts of window manipulation routines available to the pro-
  20.    grammer: auxiliary windows may be created, edited, moved and deleted. The
  21.    terminal may be set in many different modes, output text may be attributed
  22.    with blink, blank, bold and reverse attributes. There are window-specific
  23.    printf- and scanf-like routines, routines for scrolling, box-drawing, win-
  24.    dow overlaying, clearing routines etc. Curses also handles terminal func-
  25.    tion keys, which is enables by calling the keypad() function.
  26.  
  27.    The handling of character attributes is different on MGA, CGA and Hercules
  28.    adapters. The package has been tested with them all. EGA has not been tes-
  29.    ted, but should also work except for special screen modes.
  30.  
  31.    For more and detailed information, see the library source codes. All curses
  32.    functions are preceded by a brief but complete description.
  33.  
  34. COMPILING
  35.    All programs that use curses facilities should include the file <curses.h>,
  36.    and during linking, the library ?curses.lib should be specified to the lin-
  37.    ker ('?' is 's', 'c' 'm' or 'l' for small, compact, medium or large memory
  38.    model respectively).
  39.  
  40. FUNCTIONS
  41.    Below is a list over the available functions, together with a brief de-
  42.    scription of what they do. In general, functions whose names start with
  43.    'w' differ from the one without 'w' (like wmove vs. move) signify that
  44.    a specific window is used. Without a 'w', sdtscr is implied. The functions
  45.    that start with 'mv' before the 'genereic' function name signify that a
  46.    cursor motion should be made before the actual work. 'mv' and 'w' combine
  47.    as expected.
  48.  
  49.    Most routines that return an int will return the manifest constant ERR if
  50.    there is a failure during execution. Routines that return a char actually
  51.    return an int, so that ERR does not conflict with the character code 0xff.
  52.    All IBM PC characters from 0 to 0xff are allowed for usage with curses.
  53.    There are (non-portable) character output routines to write the special
  54.    IBM fonts for characters with ASCII code less than 0x20 (control charac-
  55.    ters).
  56.  
  57.    Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a meaningful
  58.    positive value if the operation is successful.
  59.  
  60.    The curses package uses some predefined types, variables and manifest con-
  61.    stants that are also available to the programmer. For example, the ERR and
  62.    OK macros should be used to test for failure of curses functions. Don't use
  63.    the numerical values, since those are different for different versions of
  64.    curses!
  65.  
  66.    There are also a few globally accessible variables that should not be tou-
  67.    ched by the application program. Those untouchable variables have names
  68.    starting with an underscore (_) to avoid conflicts. The user-accessible
  69.    types, variables and constants are (there are a number of other constants
  70.    defining character attribute names and function key names - consult the
  71.    <curses.h> and <curspriv.h> include files for details):
  72.  
  73.    (manifest constants)
  74.  
  75.        TRUE                boolean true
  76.     FALSE                boolean false
  77.     ERR                unsuccessfull operation
  78.     OK                successfull operation
  79.  
  80.    (types)
  81.  
  82.        WINDOW                a window structure type
  83.     bool                boolean flag type
  84.  
  85.    (variables)
  86.  
  87.        WINDOW curscr            physical display image
  88.     WINDOW stdscr            default user drawing board
  89.        int    LINES            terminal height
  90.     int    COLS            terminal width
  91.  
  92.    The following is an alphabetical list of the curses functions, together
  93.    with their types, parameters and a short comment for each. Win is a win-
  94.    dow; ch, l, r, t, b, tl, tr, bl and br are characters; buf is a character
  95.    buffer; attrs is an attribute bit map; bf is a boolean flag. Note that
  96.    `character' return values in this context usually are 16 bits. Guaranteed
  97.    portable functions are marked with an asterisk (*):
  98.  
  99.  
  100. *  int   addch(ch)            put char in stdscr
  101.    int     addrawch(ch)            put raw char in stdscr
  102. *  int     addstr(str)            put string in stdscr
  103.    void     attroff(attrs)            clear attribute(s) in stdscr
  104.    void     attron(attrs)            add attribute(s) in stdscr
  105.    void     attrset(attrs)            set stdscr char attributes
  106.    int     baudrate()            dummy for compatibility
  107.    void     beep()                ring the bell
  108.    void     border(l,r,t,b,tl,tr,bl,br)    Set non-std box characters
  109. *  void     box(win,l,t)            box in a window, with given characters
  110. *  void     cbreak()            set terminal cbreak mode
  111. *  void     clear()            clear stdscr
  112. *  void     clearok(win,bf)        marks window for screen clear
  113. *  int     clrtobot()            clear end of stdscr
  114. *  int     clrtoeol()            clear end of line in stdscr
  115. *  void     crmode()            set terminal cbreak mode
  116.    void     cursoff()            turns off hardware cursor
  117.    void     curson()            turns on hardware cursor
  118.    void     def_prog_mode()        save TTY modes
  119.    void     def_shell_mode()        compatibility dummy
  120. *  int     delch()            delete a char in stdscr
  121. *  int     deleteln()            delete a line in stdscr
  122. *  void     delwin(win)            delete a window or a subwindow
  123.    void     doupdate()            update physical screen
  124. *  void     echo()                set terminal echo mode
  125. *  int     endwin()            cleanup and curses finitialization
  126. *  void     erase()            erase stdscr
  127.    int     erasechar()            return char delete character
  128.    int     fixterm()            dummy for compatibility
  129.    void     flash()            flash terminal screen
  130.    void  flushinp()            kill pending keyboard input
  131. *  int     getch()    (#def macro)    get character via stdscr
  132. *  int     getstr(buf)            get string via stdscr to a buffer
  133. *  void     getyx(win,y,x)            get a window's cursor position
  134. *  int     gettmode()            dummy for compatibility
  135.    void     idlok(win,bf)            dummy for compatibility
  136. *  int     initscr()            curses initialization (ret 1 if OK)
  137. *  int     inch()                get char at stdscr cursor
  138. *  int     insch(ch)            insert character in stdscr
  139.    int     insrawch(ch)            insert raw character in stdscr
  140. *  int     insertln()            insert an empty line in stdscr
  141.    void     keypad(win,bf)            marks a window for keypad usage
  142.    int   killchar()            return line delete character
  143. *  void     leaveok(win,bf)        marks window for cursor 'update leave'
  144. *  char *longname()            returns terminal description string
  145.    void  meta(win,bf)            marks window for meta (dummy function)
  146. *  int     move(y,x)            move cursor in stdscr
  147. *  int     mvaddch(y,x,ch)        move & put char in stdscr
  148.    int     mvaddrawch(y,x,ch)        move & put raw char in stdscr
  149. *  int     mvaddstr(y,x,str)        move & put string in stdscr
  150.    int     mvclrtobot(y,x)        move & clear end of stdscr
  151.    int     mvclrtoeol(y,x)        move & clear lineend in stdscr
  152. *  int     mvcur(oldy,oldx,y,x)        move terminal cursor to <y,x>
  153. *  int     mvdelch(y,x)            move & delete a char in stdscr
  154.    int     mvdeleteln(y,x)        move & delete a line in stdscr
  155. *  int     mvgetch(y,x)            move & get char to stdscr
  156. *  int     mvgetstr(y,x,buf)        move & get string via stdscr to buffer
  157. *  int     mvinch(y,x,)            move & get char at stdscr cursor
  158. *  int     mvinsch(y,x,ch)        move & insert char in stdscr
  159.    int     mvinsrawch(y,x,ch)        move & insert raw char in stdscr
  160.    int     mvinsertln(y,x)        move & insert new line in stdscr
  161. *  int     mvprintw(y,x,fmt,args)        move & print string in stdscr
  162. *  int     mvscanw(y,x,fmt,args)        move & get values via stdscr
  163. *  int     mvwaddch(win,y,x,ch)        move & put char in a window
  164.    int     mvwaddrawch(win,y,x,ch)    move & put raw char in a window
  165. *  int